home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / printer / jcosub26.zip / JSCRIPTS.DOC < prev    next >
Text File  |  1997-05-03  |  65KB  |  1,241 lines

  1. JACOsub 2.6b SCRIPT FILE FORMAT SPECIFICATION
  2. =============================================
  3.  
  4. Here is the complete JACOsub script file format specification.
  5. It's not complicated (unless you want it to be) and quite flexible.
  6. Check out the sample script (demo.js) that came with this software;
  7. it demonstrates many of the things you can do with a script.
  8.  
  9. The accompanying file QuickRef.doc is a summary of this document, providing
  10. brief descriptions of the commands, escape codes, and directives that you
  11. can put into a script.
  12.  
  13. CONTENTS OF THIS DOCUMENT
  14. =========================
  15.  
  16.  1.  Basic format conventions
  17.  2.  Compiler commands
  18.  3.  Timed lines
  19.  4.  Directives (for controlling timed lines)
  20.  5.  Sample lines
  21.  6.  Credits
  22.  
  23. Most of the information in this document is demonstrated by the timed
  24. script demo.js, which is included in the JACOsub distribution archive.
  25.  
  26.  
  27. 1.  BASIC FORMAT CONVENTIONS
  28. ============================
  29.  
  30. 1.  Space characters (white space) may consist of spaces or tabs.  Any line
  31.     in a script file may contain any amount of white space in front of,
  32.     behind, or in between parameters or words.
  33.  
  34. 2.  A line cannot be more than 511 characters in length (but you can
  35.     concatenate several lines; see "escape codes" below).
  36.  
  37. 3.  Lines in the file may be blank lines, compiler commands, or timed
  38.     lines for the script.  All these are explained below.
  39.  
  40. 4.  Blank lines or lines containing white space only are ignored.
  41.  
  42.  
  43. 2.  COMPILER COMMANDS
  44. =====================
  45.  
  46. Any line where # is the first non-space character is treated as a compiler
  47. command.  The command is indicated by the next character or word (upper or
  48. lowercase) following the #.  Some commands have arguments, which are
  49. assumed to begin with the next non-whitespace characters following the
  50. command.  Anything shown here in square brackets [] are optional.
  51. The commands are:
  52.  
  53.    #       (followed by a space) Comment.  The line will be ignored.
  54.  
  55.            Example:
  56.            # This is a comment.
  57.  
  58.    #C[LOCKPAUSE] <time>
  59.            While a script is running, this command forces the clock to
  60.            pause the clock at the time specified by <time>.  Pressing a key
  61.            will resume play.  <time> is an offset from the beginning of the
  62.            script in the form H:MM:SS.FF (hours:minutes:seconds.units).
  63.            The beginning time of a script is usually 0:00:00.00 unless the
  64.            script was included with an offset using the #I command.
  65.  
  66.            This command is useful for titling multiple laserdisc sides in
  67.            a single script.  Be warned:  There will be no indication on the
  68.            screen telling you that the script is paused!  You have to keep
  69.            track of your pauses yourself.
  70.  
  71.    #D[IRECTIVE][n] <directive string> [optional_name]
  72.            Change some directive defaults (see the Directives section
  73.            below), for example:
  74.  
  75.            #D CF10F2  small_red_text
  76.            #directive3 hr50vmf2
  77.            #d9JLJBC
  78.  
  79.            This command affects only those lines following it.  Scripts may
  80.            contain as many #D commands as you like.
  81.  
  82.            There are 31 default directives available, D0 through D30.
  83.            Specifying #D is the same as #D0 -- this sets the general
  84.            overall default directive when a title line contains no
  85.            directive or when just the D directive is present.  The
  86.            directives D1 - D30 may be set for situations when you need a
  87.            shorthand way to represent a long complicated directive string
  88.            in many places in your script.  Directives D0-D30 are initially
  89.            all identical, according to your DIRECTIVE config setting.
  90.  
  91.            Instead of a long cryptic directive in your timed lines, you
  92.            may use the short codes you define, like D, D1, D2, etc.
  93.            Alterately, you may also assign sensible names to your directive
  94.            definitions and use these names instead of the codes D3, D4,
  95.            etc.  If you use a directive name instead of the actual
  96.            directive code in your title, you must enclose the name in
  97.            square brackets [].  The name definition in the #D command must
  98.            NOT contain brackets.  The name will be truncated after 20
  99.            characters, and uppercase or lowercase doesn't matter.
  100.  
  101.    #F[ONT] <n> <fontname.font> <size> [CLEAN or QUICK&DIRTY] [Y/X]
  102.            This command sets font <n> to <fontname.font> which is <size>
  103.            pixels high.  Font settings affect the entire script.  The <n>
  104.            argument may range from 0 to 9 if the software has been
  105.            registered, otherwise <n> may range from 0 to 3.  #F commands
  106.            should be specified before any timed lines in the script.
  107.  
  108.            CLEAN or QUICK&DIRTY indicate the rendering mode for the font.
  109.            Normally, you should NEVER need to set the rendering mode!  The
  110.            program is smart enough to determine the best mode.  Mono-color
  111.            fonts will always be QUICK&DIRTY, and color fonts will be CLEAN
  112.            only if the characters are designed to overlap.
  113.  
  114.            The rest of the arguments apply to the Amiga only:
  115.  
  116.            The Y/X argument modifies the default 1/1 aspect ratio for the
  117.            font's height vs. width.  It must be specified as two integers
  118.            separated by a slash with no spaces, as in 40/33.  This argument
  119.            works only in AmigaDOS versions 2.0 or higher.
  120.  
  121.            NOTE:  Due to the Amiga's internal font management, the Y/X
  122.            parameter will affect only those fonts having names and/or sizes
  123.            different from those fonts already loaded in memory.  For
  124.            example, the 36-pixel JACOsub font is loaded as font 0 when the
  125.            program starts up, and its aspect ratio will be whatever it had
  126.            when it loaded (see the FONT setting in the jacosub.cfg file).
  127.            Any attempt to assign "jacosub.font 36" a different aspect will
  128.            have no effect.  You can get around this by setting the program
  129.            configuration so that font 0 is something like Topaz 9,
  130.            rebooting, and then using your script to load jacosub.font 36
  131.            with the desired aspect ratio.
  132.  
  133.            Example: #F 2 Diamond.font 20
  134.  
  135.    #H[RES] <resolution mode>
  136.            This sets the horizontal display resolution mode (HIRES or
  137.            SUPERHIRES) that is expected to be used with the script.  This
  138.            should be set in the program configuration; set it in the script
  139.            ONLY if the script is designed specifically for a particular
  140.            resolution mode.  SUPERHIRES will be ignored on computers
  141.            incapable of it.  This command will be ignored if it occurs
  142.            after the first timed line, or inside #Included scripts.
  143.  
  144.            On Amigas, a typical HIRES mode is 640x400.  A typical
  145.            SUPERHIRES mode is 1280x400.  Under MSDOS, HIRES is 640x400,
  146.            and SUPERHIRES is 800x600.
  147.  
  148.    #I[NCLUDE] <time> <filename>
  149.            Include another script file <filename> into the current script,
  150.            offsetting the second script's start time by <time>.  <time> is
  151.            always FORWARD offset.
  152.  
  153.            This command is useful, for example, if you are subtitling a
  154.            series of TV shows having subtitles for credits and ending song
  155.            lyrics.  Rather than importing and/or re-timing the same
  156.            sequences over and over again for each episode, you need only
  157.            time the song lyrics once and the credits once, with the times
  158.            starting at zero, and save these two scripts as separate files.
  159.            When your "main" script includes these other scripts, they will
  160.            be incorporated properly into the main script to start at the
  161.            proper time (which is <time> added to the first time event in
  162.            the included script), and any overlapping time ranges will be
  163.            interwoven properly.
  164.  
  165.            <time> is specified in the form H:MM:SS.FF, where H is an hours
  166.            digit, M is a minutes digit, S is a seconds digit, and F is a
  167.            fractional-second digit.  The units of F are determined by the
  168.            #T command (below), and default to 30 units/second if the #T
  169.            command was omitted (that is, the FF digits are SMPTE units
  170.            ranging from 00 to 29).  The included script may in turn contain
  171.            its own, possibly different, #T command, and also its own
  172.            #I commands.  <time> always offsets the "includee" relative to
  173.            the beginning of the "includer," taking into account the
  174.            "includer's" own offset if the "includer" was itself included by
  175.            some other script.
  176.  
  177.            <filename> may be any valid path + file name.  <filename> can
  178.            specify a complete path; if no path is specified then JACOsub
  179.            will look in the default scripts directory, which you can set in
  180.            the General Config menu.  If you omit the extension in
  181.            <filename>, then the program will include the script with the
  182.            most recent time-stamp, among the extensions .js, .tts, .pjs, or
  183.            .tim (.jsc, .pan, or .sub files won't be considered).  The file
  184.            name must not contain any spaces.
  185.  
  186.            Any occurrences of #F, #P, #Q, and #R in an included script will
  187.            be ignored.  These commands work only in the primary script, and
  188.            they affect all included scripts.  The effects of #D, #S, and #T
  189.            commands are passed down into included scripts, but these
  190.            commands inside an included script affect only that script and
  191.            others IT might include; they have no effect on the higher-up
  192.            "calling" scripts.
  193.  
  194.            Example: #I 0:21:44.16 scripts:kor/kor-credits.js
  195.  
  196.    #P[ALETTE] <color> <r> <g> <b> [palette]
  197.            This sets the red, green, and blue intensities for color
  198.            register <color> (0-15), to <r>, <g>, and <b>, respectively.
  199.            RGB intensities may be specified in decimal (0 to 15) or
  200.            hexadecimal (0 to f).  If any of the values <r>, <g>, or <b>
  201.            are 16 or higher, the palette specification is assumed to be
  202.            24-bit (i.e. RGB intensities from 0 to 255 decimal, or 00 to ff
  203.            hexadecimal).  Hex numbers may be upper or lowercase.
  204.  
  205.            #PALETTE may be specified anywhere in the file, but the setting
  206.            will be used for the entire script.  Use RGB values 14 or higher
  207.            (24-bit: 238 dec, EE hex) with caution, as these are stronger
  208.            than normal video signals, and can result in color bleeding when
  209.            using in your genlocked video signal.
  210.  
  211.            Do not redefine color 2; JACOsub expects it to remain black.
  212.  
  213.            The optional [palette] parameter defaults to 0, and indicates
  214.            the palette number in which to set the color.  JACOsub has 10
  215.            palettes available.  All 10 palettes are initialized to initial
  216.            values set in the Playing / video Config menu.  Palettes 1 - 9
  217.            may be used to reset temporarily certain colors for a particular
  218.            display, using the CP directive.  If JACOsub is using a
  219.            2-bitplane display, for example, you are restricted to 4 colors
  220.            at any one time, but using multiple palettes allows you to
  221.            redefine them on the fly.
  222.  
  223.            Examples:
  224.            #P1 14 14 6    # set color 1 to yellow, in default palette 0
  225.            #P1 d d 6      # same as above, using hexadecimal RGB values
  226.            #p 3 0 13 0 1  # set color 3 to green, in palette 1
  227.  
  228.    #Q[UANTIZE] [n]
  229.            This command has the effect of eliminating timing gaps between
  230.            subtitles of less than [n] time units, as specified by the #T
  231.            command.  Default is #Q0.  Example:  With #t30 and #q2
  232.            specified, any time event less than 2/30 seconds earlier than
  233.            another time event will be rounded up to the later event.  This
  234.            is of questionable usefulness.  If this command occurs before a
  235.            #T command, then 30 units per second is assumed.  Subsequent #Q
  236.            commands replace earlier ones.  Only the last #Q command in a
  237.            script has any effect.
  238.  
  239.    #R[AMP] <seconds.units>
  240.            If you play a pre-timed script, and discover a time drift, then
  241.            use this command.  The parameter <seconds.units> is the amount
  242.            of drift to correct over the entire script.  Script timings will
  243.            be adjusted appropriately according to this value.  A positive
  244.            value will lengthen the total script running time, and a
  245.            negative value will shorten the total script running time.  The
  246.            default value is #R0.  The number after the decimal point is NOT
  247.            a fractional second; it is the number of time units specified by
  248.            #T.  THIS COMMAND MUST NOT OCCUR BEFORE A #T COMMAND.  Examples:
  249.  
  250.            #R-3.60  will shorten the script running time 3 seconds plus 60
  251.                     time units.
  252.            #R .92   will lengthen the script running time 92 time units.
  253.  
  254.            IMPORTANT:  Genlocks may affect the computer's internal clock.
  255.                        If you find that you have to ramp a 30-minute script
  256.                        more than 10 seconds, then you have a bad problem
  257.                        with your genlock.  DO NOT TRY TO "FIX" THE PROBLEM
  258.                        WITH A BIGGER RAMP TIME!  Doing so will result in
  259.                        math overflows, causing sudden jumps in timing.
  260.  
  261.    #S[HIFT] <[[hours:]minutes:]seconds.units>
  262.            The parameter <seconds.units> is the amount to shift each time
  263.            event in the script.  A positive value will delay each time, and
  264.            a negative value will advance each time.  The default value is
  265.            #S0.  The number after the decimal point is NOT a fractional
  266.            second; it is the number of time units specified by #T.  THIS
  267.            COMMAND MUST NOT OCCUR BEFORE A #T COMMAND.
  268.  
  269.            The first occurrence of #S in a script determines a global
  270.            amount of shift, even if the first #S appears AFTER some timed
  271.            lines.  Subsequent occurrences affect only those lines following
  272.            the #S.  You must take care that your #S commands do not cause
  273.            any times to be less than zero.  The Amiga uses unsigned
  274.            integers (always positive) for its internal representation of
  275.            times, meaning that a time "less than" zero is actually a very
  276.            large number!
  277.  
  278.            Example:  #S -0.20 will cause ALL events to occur 20 time units
  279.            sooner than usual, if this is the FIRST #S.  Otherwise, all
  280.            events SUBSEQUENT to this command will be shifted so that they
  281.            occur 20 units sooner.
  282.  
  283.    #T[IMERES] <n>
  284.            Time resolution; sets time units to <n> per second.  The default
  285.            is SMPTE units of 30 counts/second, as in #T30.  If your script
  286.            is in units 1/100 second units or PAL units, you must say so
  287.            with the appropriate command, before the subtitle text begins.
  288.            The #R or #S commands cannot precede a #T command.
  289.  
  290.            Examples:  #t100
  291.                       #TIMERES 25
  292.  
  293.  
  294. 3.  TIMED LINES
  295. ===============
  296.  
  297. Timed lines for the script may occur in any order.  They look similar to
  298. this:
  299.  
  300.    H:MM:SS.FF H:MM:SS.FF directive {comment} text {comment} more text...
  301.  
  302. For example:
  303.  
  304.    0:30:57.22 0:30:59:46 vm {opening credit} A Film By Akira Kurosawa
  305.  
  306. Here's what all those pieces are:
  307.  
  308. Start time and stop time
  309. ------------------------
  310. The first field is the time when the subtitle is to appear on the screen.
  311. The normal default is SMPTE format (that is, FF can range from 00 to 29).
  312. Use the #T command (described above) to define the units.  IMPORTANT: The
  313. FF digits represent time units, NOT fractions of a second.  There is a
  314. difference!  For example, if you use #T10 to specify 1/10 second time
  315. units, then a time such as 0:00:00.60 would be illegal (and result in an
  316. error) because it specifies 60 time units!  0:00:00.6 or 0:00:00.06 or
  317. even 0:00:00.00006 would be correct for this case -- 6 UNITS are specified,
  318. not 6 tenths of a second.
  319.  
  320. The second field is the time when the title is to disappear.
  321.  
  322. If you prefer, you do not have to use the H:MM:SS.FF format at all.
  323. Instead, you can substitute a @ symbol followed by a single integer to
  324. represent total time units.  For example, if #T30 is used to specify 1/30
  325. second units, then the 0:05:10.22 is the same as @9322.  This format is
  326. useful for representing times as video frame counts.  Many laserdisc
  327. players display times in this fashion.
  328.  
  329. Directive string
  330. ----------------
  331. The next field is the directive.  It is optional.  If you leave it out, the
  332. program will default to standard subtitling form (all text centered at the
  333. bottom of the screen or depending on how you have your global default
  334. directive set in your configuration).  The title text MUST begin with a
  335. non-alphabet character {such as a comment} if you omit the directive.
  336. Directives are explained fully in the DIRECTIVES section below.  The first
  337. non-whitespace character following  the directive is assumed to be the
  338. beginning of the subtitle text.
  339.  
  340. Inline comments
  341. ---------------
  342. The {comment} is considered a part of the subtitle text, but it is ignored
  343. by the software.  Use it for character names or keywords.  A comment must
  344. be enclosed in braces.  Comments may appear anywhere within the text of a
  345. subtitle.  If you really want to to display a left brace, precede it with a
  346. backslash like so: \{.  Right braces will be interpreted as a literal
  347. character or close of a comment, whichever seems appropriate.  If a
  348. whitespace character immediately follows a comment closing brace, then that
  349. first whitespace character will be ignored.  Any other kind of following
  350. character will be considered part of the subtitle text, and used.  Comments
  351. in the text are especially useful when translating foreign films -- we use
  352. them to list possible translations of phrases we are not yet sure about.
  353.  
  354. Title text
  355. ----------
  356. In the example above, the "text" and "more text" fields are what get
  357. displayed.  There are several special codes that you can put inside the
  358. text (in JACOsub scripts, CASE MATTERS ONLY IN THESE CHARACTER CODES):
  359.  
  360. Special character codes:
  361.  
  362.    \    Concatenate.  If the LAST character in a line is a backslash, then
  363.         JACOsub will concatenate the text on the next line to the text
  364.         in the current line.  Leading and trailing whitespace will be
  365.         stripped from the concatenated text, so you can indent it if you
  366.         wish.
  367.  
  368.    \n   Newline.  This is like a carriage return.  A line containing this
  369.         code will be split at the \n.  Each of these new fragments will
  370.         then be wordwrapped separately unless you turn wordwrapping off
  371.         (see the W directive below).  \n is useful for general formatting.
  372.         Multiple \n codes may be concatenated to create blank lines.
  373.         Example:  Hello!\n\nHow are you?{blank line separating the two}
  374.  
  375.    \{   Display a left brace.  Left braces are normally used to indicate
  376.         the beginning of a comment.
  377.  
  378.    \~   Display a tilde.  Tildes are normally used to create "hard" spaces
  379.         (see below).
  380.  
  381.    \\   Display a backslash.  Backslashes are normally used to denote these
  382.         special codes.
  383.  
  384. Insertions:
  385.  
  386.    \D   Insert current date into the title.  The date will be of the format
  387.         DD MMM YYYY, as in 2 Apr 1996.
  388.  
  389.    \T   Insert current time into the title.  The time will appear as HH:MM
  390.         (24-hour time).
  391.  
  392. Font codes:
  393.  
  394.    \N   Normal.  All text appearing after this code will be displayed in
  395.         "normal" style.  This is typically the default, unless you have the
  396.         style (S) directive set to something other than normal.  Note that
  397.         this code is an uppercase \N -- a lowercase \n is a newline code.
  398.  
  399.    \I   Italics on.  Display all text appearing after this code in italics.
  400.         Example:  \IHello!\N\nHow are you?{Hello is in italics}
  401.    \i   Italics off.  \N does the same thing, turning off all font styles.
  402.  
  403.    \B   Boldface on.  This one isn't particularly useful, but go ahead if
  404.         you feel like it.  Text characters will be slightly fatter.
  405.    \b   Boldface off.
  406.  
  407.    \U   Underline on.  This is virtually useless for large color text.
  408.    \u   Underline off.
  409.  
  410.    \Cn  Color n.  The text following this code will be displayed using face
  411.         color n.  n is a hexadecimal digit; it may take the values 0-9 or
  412.         A-F (or a-f).  Typically, when using the font supplied with this
  413.         software on a 2-bitplane display, only colors 3 and 1 are useful.
  414.         See the CF directive below for some caveats about colors.
  415.  
  416.    \Fn  Font n.  The text following this code will be displayed using font
  417.         number n.  n may range from 0 to 9 (or 0 to 3 if the program is
  418.         not registered).  Normally you would use the F directive to set the
  419.         default font for a line; use this escape code to override it.
  420.  
  421. THE FONT CODES ABOVE AFFECT ONLY ONE TIMING LINE; their effects do not
  422. carry over into other lines.  These codes override any directives.  The \I,
  423. \B, and \U codes were mutually exclusive in versions prior to 2.6.  Now,
  424. the styles may be combined, for example:
  425.  
  426.    This is \B\Ibold italic\i\b text.
  427.  
  428. \N turns off all styles.  See the demo script file (demo.js) for additional
  429. examples on usage.
  430.  
  431. Leading or trailing space in subtitle text will be ignored.  If you want to
  432. encode a true space on the ends of some text, use a tilde (~).  It will be
  433. displayed as a space.  To actually display a tilde, precede it with a
  434. backslash: \~.  Tildes may also be used to create "hard" spaces; they will
  435. be displayed as spaces but text will not be wordwrapped on these spaces.
  436.  
  437. White space between line arguments may consist of any amount of spaces or
  438. tabs.  Each tab character inside the subtitle text will be converted to a
  439. space character.
  440.  
  441.  
  442. 4.  DIRECTIVES
  443. ==============
  444.  
  445. Directive strings were briefly described above, but there are so many that
  446. they deserve to be allocated a whole section of this document.
  447.  
  448. A directive is a series of character codes strung together.  A directive
  449. determines a subtitle's position, font, style, color, and so forth.  Each
  450. character code begins with an alphabet character followed by arguments made
  451. up of other alphabet characters and numbers.  Directives may contain any of
  452. the following codes, in any order.  The directives may be uppercase or
  453. lowercase.  Like the text codes above, directives only affect a SINGLE
  454. timing line; their effects do not carry over into other lines.  Any
  455. parameters shown here in square brackets [] are optional.
  456.  
  457. Vertical positioning
  458. --------------------
  459.  
  460.     VA     Continue this line directly Above the previous one.  This is
  461.            the opposite behavior of VU below.  This is a useful directive
  462.            for those cases where you want a new line to appear above the
  463.            previous line's position, even if both lines do not share the
  464.            same time range.  See VU below for more details.
  465.  
  466.     VB[n]  Bottom.  Position last line at the bottom (default).  The offset
  467.            from the bottom of screen n is optional  - it says how many
  468.            raster lines to offset from the physical bottom-of-viewport.  VB
  469.            by itself is the same as VB16 (in the original default for this
  470.            software).  The default value of n can be changed using #D
  471.            command or in the General Configuration settings.
  472.  
  473.     VHn    Line height (i.e. spacing), where n is the percentage of the
  474.            font height to use for line spacing.  Default is 100 (single-
  475.            spaced).  Using 200 would result in double-spaced lines.  n may
  476.            range from -32768 to 32767, although the useful range is
  477.            probably more like 50 to 500.
  478.  
  479.     VL[n]  line n. Position subtitle starting at text line n (the height
  480.            of a line depends on the font you use).  n=0 is the top line.
  481.            If n is negative or omitted, the line will appear in the same
  482.            vertical position as the preceding timed line.
  483.  
  484.     VM[n]  Middle.  Text will be centered vertically in the area defined by
  485.            the VTn and VBn directives.  The optional parameter [n] is a
  486.            positive or negative integer that will cause the centered block
  487.            to be shifted up or down [n] lines (line height determined by
  488.            the VH setting).
  489.  
  490.     VPn    Pixel n. Position subtitle so that the font baseline of the
  491.            first line of text is n pixels from the top of the viewport.
  492.            You need to know your font's baseline position for this
  493.            directive to be of any use.  The mouse-positioning operation in
  494.            the script editor creates directives like this.
  495.  
  496.     VS[n]  Scroll at speed n (default -2).  n<0 is number of frames to wait
  497. (Amiga)    per raster line scrolled.  n>0 is number of raster lines to
  498.            scroll per frame.  n may range from -6 to 4, with the values -1,
  499.            0, and 1 all treated the same.  Text will scroll in from the
  500.            bottom of the display and scroll off the top.  If the start time
  501.            of scrolled text is the same as the end time of the previous
  502.            view, the previous view will be scrolled off as the new text is
  503.            scrolled in.  The new text to be scrolled in will begin at an
  504.            offset below the bottom edge of the screen, controlled by the VT
  505.            offset quantity.
  506.  
  507.            IMPORTANT CONSIDERATIONS FOR VERTICAL SCROLLING DIRECTIVE:
  508.            1.  Overlapping time ranges are ignored, except for
  509.                concatenations caused by VU directives.  Use the VU
  510.                directive to concatenate title paragraphs, otherwise use the
  511.                end-of-line concatenation escape character (\).
  512.            2.  Be sure you give the titles sufficient duration for the
  513.                scrolling to complete -- if the duration is too short,
  514.                scrolling will complete anyway, delaying anything scheduled
  515.                to happen immediately afterward.
  516.            3.  The only really useful scrolling speeds are -2 or less.
  517.                Speeds of 2 or higher are almost too fast to read anything,
  518.                and the maximum speed of 4 is usually too fast for the
  519.                program to keep up with.  Speeds -1, 0, and 1 (all treated
  520.                the same) result in strange distortions due to the fact that
  521.                the video is interlaced.  This fact, combined with an odd-
  522.                numbered scroll at every video refresh, causes only every
  523.                other line in the bitmap to be visible during the scroll.
  524.            4.  Regardless of whether the speed is even or odd, positive
  525.                speeds that do not divide evenly into your screen height
  526.                will be reduced to the next lower speed that does divide
  527.                evenly.
  528.            5.  The following directive prefixes will be ignored:
  529.                E, CS, FC, FD, FO, FS, FQ, I, and R.
  530.            6.  Scrolling may not be smooth for large fonts or color fonts,
  531.                or it may be smooth but the text may not be generated
  532.                rapidly enough to keep up with the scroll.  Either way, the
  533.                program will warn you if you try to scroll a color font.  It
  534.                works best with small-to-medium sized mono-color fonts.
  535.            7.  Under AmigaDOS 1.3 and below, fonts with slightly
  536.                overlapping bitmaps may not be spaced properly.  The program
  537.                will warn you of this if you try it under 1.3.
  538.            8.  The VU directive may be used after VS to append more text.
  539.                You should use VU to concatenate paragraphs of scrolling
  540.                titles.  This is more memory-efficient than using the \
  541.                concatenation code at the end of each line.
  542.            9.  You can use embedded codes to change text style and color,
  543.                but be careful changing fonts in the middle of a line.
  544.                Changing fonts works best if the new font is on a separate
  545.                line all its own, or if the new font is the same size as
  546.                other fonts on the same line.
  547.           10.  This directive uses a significant amount of display memory;
  548.                equivalent to slightly more than two additional display
  549.                buffers.  Insufficient RAM will cause scrolled titles to be
  550.                skipped.  Sometimes the scrolling bitmap will fail to
  551.                allocate from fragmentation in the available display memory.
  552.                Shutting down the program and restarting it might alleviate
  553.                this fragmentation enough to facilitate scrolling.
  554.  
  555.     VT[n]  Top.  Position the title with the first line at the top.  The
  556.            offset n is optional - as with VB, VT by itself is the same as
  557.            VT16 in the original distribution of this software.
  558.  
  559.     VU     Continue this line directly Underneath the previous one.  This
  560.            is useful if you want a line with different directives grouped
  561.            in the same vertical-positioning block as the previous line.
  562.            It's like the line-concatenation escape code (\) only it doesn't
  563.            continue the previous line where it left off, but instead starts
  564.            a new line below it, positioning the previous line higher, if
  565.            necessary, to make room for the new line.
  566.  
  567.            You can also use the VU directive to create interesting effects
  568.            when a line with the VU directive does not share the same time
  569.            range as the previous line.  For example, suppose you had a
  570.            single line that used the VM directive.  Normally it would be
  571.            perfectly centered vertically on the screen.  However, if a VU
  572.            line follows it, both are positioned as if they were a single
  573.            block of lines to be centered on the screen together; i.e. the
  574.            VM line will appear slightly above center and the VU line will
  575.            appear slightly below center, regardless of WHEN they are
  576.            individually displayed.  Had VB been used instead of VM, the
  577.            first line would have appeared raised one text line higher than
  578.            bottom, just enough to make room for the second line.  VA has
  579.            the same effect as VU if the lines are reverse-ordered in the
  580.            script.
  581.  
  582. Horizontal positioning
  583. ----------------------
  584.  
  585.   Margins:
  586.  
  587.     HLn    Left margin.  Set left margin at a position that is n% of the
  588.            the screen width.  Default is HL1 (1% from left edge).  Minimum
  589.            value is -128 (way past the left edge of the display area).
  590.  
  591.     HRn    Right margin.  Set the right margin at a position that is n% of
  592.            the screen width.  Default is HL99 (1% from right edge).  The
  593.            right margin MUST be greater than the left margin.  Maximum
  594.            value is 127, although anything greater than 100 is useless.
  595.  
  596.   Text justification:
  597.  
  598.     JC     Center.  Text is centered within H constraints (normal default).
  599.  
  600.     JF[:p] Full.  This aligns the left and right edges of text flush with
  601.            the ends of the widest wordwrapped line in the text block.  If
  602.            you want the justified text to span the full margin width, set
  603.            wordwrapping to W2 (greedy) instead of W1 (smart, the default).
  604.            The :p is a position parameter.  It may be :C (default), :L, :R,
  605.            or :U, for Center, Left, Right, and Unconditional, respectively.
  606.            :C, :L, and :R control the position of non-wordwrapped lines
  607.            such as single short lines or the last line in a wordwrapped
  608.            block -- these will not not be stretched to fit the block width.
  609.  
  610.            (Remember, \n codes delimit wordwrapped blocks; a title split
  611.            by \n codes will wrap and justify each section as if they are
  612.            completely separate titles.  If you want to justify a title
  613.            properly, you should remove all \n codes except for where the
  614.            wrapping and justifying should end.)
  615.  
  616.            The :U parameter means "unconditional."  JF:U is the same as JU.
  617.            JF:U causes ALL lines in the block, wordwrapped or not,
  618.            including the last line, to be stretched to fit exactly within
  619.            the margins.  JF:U is useful for titling credits like this:
  620.  
  621.                   Clint Eastwood . . . . . . . Dirty Harry
  622.  
  623.            All the spaces will then be adjusted so that the line fits
  624.            exactly inside the margins, and a list of these credits will
  625.            have flush left and right edges.  You will need to experiment
  626.            with the number of dots and spaces to get it all to look good.
  627.            You can also try elminating the spaces between the dots, or
  628.            substituting dashes, for somewhat different effects.
  629.  
  630.            JF[:p] commandeers one character in each proportional font for
  631.            use as an adjustable space; the decimal character code used will
  632.            be one of: 128, 31, or 127, whichever is available (hex codes
  633.            80, 1F, or 7F, respectively).  The JF directive has no effect on
  634.            fonts lacking all of these character codes.  Mono-spaced fonts
  635.            are likewise unaffected.
  636.  
  637.     JL     Left.  Align left edge of text at the HLn margin position.
  638.  
  639.     JR     Right.  Align the right edge of text at the HRn margin position.
  640.  
  641.     JU     Obsolote directive; identical to JF:U
  642.  
  643.   Block justification:
  644.  
  645.     JBC    Justify block center.  Because of wordwrapping, the width of a
  646.            text block will never occupy the full width specified in your
  647.            margin settings.  This directive positions the imaginary
  648.            rectangle occupied by the text in the center of your margin
  649.            settings, regardless of the text justification directives.  For
  650.            example, the JL directive by itself might produce the following
  651.            effect (the | character indicates margin boundaries):
  652.  
  653.            | The quick brown fox                      |
  654.            | jumped over the lazy dog.                |
  655.  
  656.            but the JL directive together with JBC will preserve the text
  657.            justification but center the block of text between the margins:
  658.  
  659.            |        The quick brown fox               |
  660.            |        jumped over the lazy dog.         |
  661.  
  662.            AnimEigo video products have their subtitles displayed this way.
  663.  
  664.     JBF    Justify block full (default).  Text will be positioned according
  665.            to whatever text justification directives are in effect, using
  666.            the full width specified by the current margin settings.
  667.  
  668.     JBL    Justify block left.  Position the text block at the left margin.
  669.  
  670.     JBR    Justify block right.  Position the text block so that the right
  671.            edge is at the right margin.
  672.  
  673.   Wordwrapping:
  674.  
  675.     W0     Disable automatic wordwrapping.  This may result in your text
  676.            not fitting within the position constraints defined with H & V.
  677.            There is really NO reason at all why you would want to turn off
  678.            wordwrapping; you can wrap words manually with the \n code
  679.            whether wordwrapping is on or off.  This directive is here just
  680.            for the sake of completeness.
  681.  
  682.     W1     Automatic "smart" wordwrapping (default).  Even if a your text
  683.            contains newline codes, the separate substrings will be word-
  684.            wrapped if necessary.  This wordwrap mode uses a "smart"
  685.            algorithm that attempts to minimize the area of the screen
  686.            occupied by the title.  In this mode, you will never see a line
  687.            wrapped as shown (the | characters indicate margin boudaries):
  688.  
  689.            | The quick brown fox jumped over the lazy |
  690.            |                   dog.                   |
  691.  
  692.            Instead, the W1 alghorithm will attempt to minimize the text
  693.            area without using any extra lines, resulting in:
  694.  
  695.            |           The quick brown fox            |
  696.            |        jumped over the lazy dog.         |
  697.  
  698.            This is easier for the viewer to read.  Same margins, same
  699.            number of lines, but the lines are more equal in length.
  700.  
  701.     W2     Automatic "stupid" (generally known as "greedy") wordwrapping.
  702.            If you are disconcerted by words not completely filling the
  703.            horizontal margin space, and you don't mind having a single word
  704.            hanging by itself on the last line (as in the first W1 example
  705.            above), then use this directive.  This is the standard
  706.            text-editor wordwrap algorithm, which makes no attempt at
  707.            aesthetics.  Why anybody would want to use this is beyond me,
  708.            but here it is.  \n codes behave the same as with W1.
  709.  
  710. Fonts
  711. -----
  712.  
  713.   Font rendering:
  714.  
  715.     Fn     Use font n, where n is a number from 0 to 9 (JACOsub loads
  716.            four fonts, which you can specify in the Config menu.  The usual
  717.            default font is 0, which is what you should use as your
  718.            "primary" font.  Fonts 4-9 are unavailable if the software is
  719.            unregistered.
  720.  
  721.     FQ     Quick&Dirty text.  Text color 3 is always quick.  Other colors
  722. (Amiga)    must normally be rendered one character at a time to avoid
  723.            interference between the shadow and face color, but only when
  724.            the font is designed with overlapping characters.  This
  725.            interference happens because of a fault in the way the Amiga
  726.            renders text.  The FQ directive forces all text on a line to be
  727.            rendered in quick mode as if it were color 3.
  728.  
  729.            You should never need to use the FQ directive.  The program is
  730.            smart enough to determine when a font can be quick&dirty.  For
  731.            example, JACOsub's 32- and 36-pixel fonts will default to clean
  732.            mode because they have overlapping characters, but the 32-pixel
  733.            font will default to Quick&Dirty because its characters do not
  734.            overlap.
  735.  
  736.     FC     Clean rendering.  Only color 3 will be rendered fast, other
  737. (Amiga)    colors will be rendered so that the face color is not disturbed.
  738.            You can use this directive to negate, on a single line, a global
  739.            FQ directive set using the #D command.  Normally this directive
  740.            will never be needed.
  741.  
  742.            The demo script demo.js tricks JACOsub into generating "slow"
  743.            clean text in the foreground display so you can see how it is.
  744.            If you are curious to see how the Amiga messes up color 1 text
  745.            if it's displayed the quick way, run the demo after inserting
  746.            the global command #DFQ at the top of the file demo.js before
  747.            you play the demo.
  748.  
  749.     FD     Default text rendering.  Rendering will be "quick" or "clean"
  750. (Amiga)    depending on how your font was set up in your configuration.
  751.            This directive is useful for overriding a #DFC or #DFQ command.
  752.  
  753.     FBn    Blitter activity.  This overrides the "Use Blitter" program
  754.            configuration setting.  If n=1, the blitter will be used to copy
  755.            text between background video buffers for titles that extend
  756.            over several time events.  If n=0, then time-overlapping text
  757.            will be generated afresh on each video buffer.  Normally, the
  758.            blitter should always be enabled.  However, blitting between
  759.            buffers will also copy any imagery behind the title (like a
  760.            graphic or shaded background), which might not share the same
  761.            time range as the title.  If this happens, then disable the use
  762.            of the blitter for that title with the FB0 directive.
  763.  
  764.     FOn[:a]  Generate an outline around the font, n pixels wide.  Color 2
  765.            (JACOsub's outline color) is used to generate the outline.  This
  766.            directive is useful for transforming a plain mono-color Amiga
  767.            font into a nice titling font, especially when combined with the
  768.            FS (font shadow) directive.  Recommended value for n is 2, which
  769.            produces a nice flicker-free outline.  n must be less than 127.
  770.            The maximum practical value is 3 or 4.  The default value is 0.
  771.  
  772.            The optional :a suffix indicates a color to use for anti-
  773.            aliasing.  This defaults to the anti-alias setting in the
  774.            Playing / video configuration, typically 2 (no antialiasing).
  775.  
  776.            WARNING:  Generating outlines can slow the program down
  777.            considerably!  It is recommended that you use this directive
  778.            only with QUICK&DIRTY font rendering, preferably with mono-color
  779.            fonts.  An antialias color other than 2 will slow it down
  780.            somewhat further.
  781.  
  782.     FSdn   Generate a font shadow, taking into account any existing font
  783.            outline, in direction d, and n pixels deep.  Color 2 (JACOsub's
  784.            shadow color) is used to generate the shadow.  The direction d
  785.            is specified as a compass direction: N, S, E, W, NW, NE, SW, SE.
  786.            Good values to use for the shadow depth n are 2 - 5.  The
  787.            warning about font outlines above applies here also.
  788.  
  789.            Example: FSSE3 produces a shadow similar to the JACOsub 32-
  790.            pixel font, with the shadow extending down and to the right.
  791.  
  792.   Font style (may also be set with \ codes in the title text):
  793.  
  794.     SN     Normal style (typical default).
  795.  
  796.     SI     Italic.
  797.  
  798.     SB     Bold (using the JACOsub font, this doesn't look good with colors
  799.            other than color 3).
  800.  
  801.     SU     Underline (ugly!  Not recommended).
  802.  
  803.     The styles SI, SB, and SU may exist in the same directive to combine
  804.     two or more styles.
  805.  
  806.   Font color (CFn may also be set with text codes):
  807.  
  808.     CFn    Use color register n for the face color of the font.  JACOsub
  809.            assumes that all color fonts use bitplane 0 (i.e. color 1) for
  810.            the face color, and bitplane 1 (i.e. color 2) for the shadow/
  811.            outline.  THIS IS IMPORTANT!  JACOsub will generate text
  812.            differently depending on the color selected (see FF above).
  813.            The foreground color may also be set using the \Cn code inside
  814.            the text.
  815.  
  816.     CBn    Use color register n for the background color.  The display
  817.            will be cleared to this color prior to building the text.  If
  818.            two lines share the same display, and they have different
  819.            background colors specified, the screen will be cleared using
  820.            the latest NON-ZERO background color that occurs for that
  821.            display.  In other words, non-zero colors override the default
  822.            zero (transparent) background color.
  823.  
  824.     CPn    Use color palette n for this display.  Default value of n is 0,
  825.            which is the primary color palette normally used by JACOsub.
  826.            The values of n may range from 0 to 9, for a total of 10 color
  827.            palettes.  All 10 palettes are initially set to a master palette
  828.            which can be modified in the Playing / video Config menu, and
  829.            they can be modified with the #Palette script command.
  830.  
  831.            Because the palette is loaded immediately following a video
  832.            buffer switch, the new imagery on the display will appear with
  833.            the old palette momentarily.  If this is too noticeable, then
  834.            you should precede your alternate-palette lines with a "dummy"
  835.            short-duration blank screen (containing a hard space) using your
  836.            alternate palette, as in this example:
  837.  
  838.            0:00:12.20 0:00:12.22 cp2 ~{palette 2 on blank screen, .02 sec}
  839.            0:00:12.22 0:00:14.50 cp2 This will appear with the new palette.
  840.  
  841.     CS[L]n[:s[:c]] This causes text to appear inside a shaded rectangle.
  842.            The rectangle will be large enough to contain the text with a
  843.            margin of n pixels on all sides.  The shading is user-defined
  844.            (see the Playing / video Config menu) if s=0, or solid if s=1.
  845.            Color c will be used for the rectangle.  The style (s) and color
  846.            (c) paramters are optional; not setting them uses the defaults,
  847.            normally s=0, c=2 (user-defined, black).
  848.  
  849.            Setting n=0 disables the shading.  We suggest using n=8 or more.
  850.            Without the [L] parameter described below, only ONE shaded
  851.            background rectangle will appear on the screen; that is, JACOsub
  852.            will attempt to create a SINGLE box which contains ALL text that
  853.            uses the CS directive and shares the same display.  If two
  854.            shading directives for the same time range have conflicting
  855.            parameters, one of the directives will be used, but predicting
  856.            WHICH one is impossible.  The normal default setting is CS0:0:2,
  857.            which can be changed using the #D command.
  858.  
  859.            The optional [L] parameter causes each text segment (which might
  860.            be split by wordwrapping) to be shaded in its own rectangle.
  861.            This looks ugly for a block of wordwrapped text, but it is
  862.            useful for shading separate single lines that overlap in time.
  863.  
  864.            Notes:  Setting VB0 will mean that bottom-positioned text is as
  865.            low as it will go, therefore shading cannot appear below it.
  866.            You should set the VB directive so that there is room for the
  867.            shading rectangle to extend below the text.  Also, VB text will
  868.            be repositioned slightly higher when the running clock is
  869.            displayed during play, but shade boxes will NOT be repositioned.
  870.  
  871. Genlock fader control (Amiga only)
  872. ---------------------
  873.  
  874.     GBn[Tm] Move the background slider control to n% saturation over a time
  875. (Amiga)    period of m/60 seconds of time.  n may range from 0 to 100.  If
  876.            time specifier is omitted, it defaults to 0 (i.e. instant).
  877.            Zero saturation is a normal transparent background, allowing the
  878.            video signal to show through all areas corresponding to color 0
  879.            on the computer's display.
  880.            Example:  GB63T120 slides the background fader to 63% saturation
  881.            in 2 seconds (120/60 seconds).
  882.  
  883.     GGn[Tm] Move the graphics slider control to n% saturation over a time
  884. (Amiga)    period of m/60 seconds of time.  100% saturation is the normal
  885.            operating mode (full graphics), whereas 0% results in only the
  886.            video signal with no overlaid computer graphics.
  887.  
  888.         >> DO NOT USE GG OR GB IN DEFUALT DIRECTIVES, or the genlock will
  889.            be having control signals sent to it at every time event.
  890.  
  891. IFF graphic files (obsolete, see R directives) (Amiga only)
  892. -----------------
  893.     IL     Same as RLB.  Retained for compatibility with previous versions.
  894.     IS     Same as RLG.  Retained for compatibility with previous versions.
  895.  
  896. Special effects
  897. ---------------
  898.  
  899. Basic information and warnings:
  900. 1.  Only one effect can exist per time event.  If two titles share the same
  901.     start time, but have different effects, only one effect will be
  902.     executed for both titles.
  903. 2.  All these effects must be given sufficient time to complete.  Any
  904.     time events that occur while the effect is in progress will be
  905.     postponed until the effect is finished executing.
  906. 3.  With the exception of effects EN or E0, and ES, an effect directive
  907.     will be ignored if the bitmaps for the current view and next view are
  908.     incompatible (having different dimensions or depth).  This is not a
  909.     problem for transitions between two normal video buffers; but the
  910.     effect will be ignored if you try to transition to a graphic screen
  911.     having different dimensions or display mode from the image currently
  912.     displayed.
  913. 3.  In the descriptions below, the "d" parameter controls the direction of
  914.     the effect, if applicable.
  915. 4.  The optional "[s]" parameter controls the speed of the effect, which
  916.     may range from 1 to 64 (default is 8 if omitted).  The speed represents
  917.     raster lines per vertical CRT blank.  If s=0 or s=?, the speed will be
  918.     randomly chosen.
  919. 5.  If you notice "roughness" in the way these effects operate, try
  920.     reducing either the effect speed or the number of colors you use for
  921.     script playback.
  922.  
  923.     EBd[s] Blinds.  New view replaces old view as if Venetian blinds were
  924.            opened.  Direction d may be V or H to specify vertical or
  925.            horizontal blinds.
  926.  
  927.     ED[s]  Dissolve.  New view replaces current view by random memory
  928.            replacement.  There are only three speeds: slow (s=0-9), medium
  929.            (s=10-19), and faster (s>20).  This is probably not the best
  930.            algorithm for a dissolve -- if anybody can write a better one,
  931.            please send it to the author.  It needs to be cleaner and
  932.            faster.  As it is, the only really useful speed is the maximum
  933.            (s>20).  The actual speed will depend on your video buffer
  934.            size (width, height, number of colors).
  935.  
  936.     EEVd[s] Reveal next view as if Eyelids open (d=O) or close (d=C)
  937.            vertically over the current view.  This is actually two
  938.            simultaneous vertical wipes in opposite directions on the top
  939.            and bottom halves of the display.
  940.  
  941.     EEHd[s] This is a horizontal-wipe Eyelid effect.  It vaguely resembles
  942.            the opening or closing of curtains.
  943.  
  944.     EId[s] Reveal next view as an Iris opening (d=O) or closing (d=C) over
  945.            the current view.
  946.  
  947.     EN     Normal transition (default).  New view replaces old.  Also E0.
  948.  
  949.     EPn[:s] Palette fade.  Transform the current title palette to palette n
  950.            in [:s] video fields.  This effect will be ignored if applied to
  951.            a graphic file.  Speed may range from 0 to 255, instead of 1 to
  952.            64, and the default speed is 32.
  953.  
  954.     EP+a[:b[:p]]
  955.     EP-a[:b[:p]]
  956.            Cycle forward (+) or backward (-) colors a through b (default b
  957.            is the maximum color index) with a period of p video fields per
  958.            cycle step (default 2).  This effect terminates at the next time
  959.            event.  [:p] may be as high as 255.
  960.  
  961.     ERd[s] Smoothly Roll the current view off the display while rolling the
  962. (Amiga)    next view in.  The direction d may be U, D, L, R (up, down,
  963.            left, right).  Caveats:
  964.            1.  This effect consumes much memory: the equivalent of two
  965.                additional video buffers.  You may have to reduce your usual
  966.                number of buffers or colors to make this effect work.
  967.            2.  Horizontal rolls (left and right) are not possible under
  968.                AmigaDOS 1.3.  They will be converted to up and down,
  969.                respectively.
  970.  
  971.     ESd[s] Scroll new view up into the display if d=U, or reveal new view
  972. (Amiga)    by scrolling current view down if d=D.  This directive will also
  973.            work if the bitmaps are incompatible, i.e., if either view is an
  974.            graphic view created by the RLG directive.  This is not a
  975.            "smooth" scroll; you may not find it acceptable.
  976.  
  977.     EWd[s] Wipe next view over current view in the given direction d (U=up,
  978.            D=down, L=left, R=right).
  979.  
  980.     E?[s]  Random transition chosen from those above, with random speed if
  981.            [s] is also a question mark (?), or zero.  Ignored for
  982.            incompatible bitmaps when applicable.  The Random effect does
  983.            not include the Palette effects.
  984.  
  985. Argument directives (using the title string as parameter arguments)
  986. -------------------
  987.  
  988.     DO NOT USE THE R DIRECTIVES IN A #D DIRECTIVE DEFINITION.
  989.  
  990.     RLB <ILBM file name> [<x offset %> <y offset %>]
  991. (Amiga)    Load an IFF graphic file (typically a brush file) into a video
  992.            buffer for the time interval specified by the start and stop
  993.            time.  When this directive appears, JACOsub assumes that the
  994.            remainder of the line is information about the file, NOT title
  995.            text.  The file name must follow the directive string.  The
  996.            position to display the image, specified as percent of screen
  997.            width and height from the center, can be specified in the next
  998.            two fields.  These position coordinates default to 0 0 if they
  999.            are omitted, which results in the picture being centered on the
  1000.            screen.  The picture may be positioned to extend beyond the
  1001.            display edge.
  1002.  
  1003.            Any IFF graphic picture or brush may be specified.  As many as
  1004.            40 images may be loaded onto a single screen.  This enables you
  1005.            to create several small brushes and display them all at once, in
  1006.            different areas of the screen.
  1007.  
  1008.            CAVEATS (READ CAREFULLY!):
  1009.            1.  You need at least AmigaDOS 2.0 to use this directive.  Under
  1010.                1.3 and below, this directive is ignored unless you have a
  1011.                1.3-compatible version of iffparse.library in your libs:
  1012.                directory.
  1013.            2.  If a file is too big to fit in memory, the file will simply
  1014.                not load, and the program will beep to alert you.
  1015.            3.  If the graphic file contains more bitplanes than the JACOsub
  1016.                video buffers, the EXTRA BITPLANES WILL BE IGNORED.  You may
  1017.                change the number of JACOsub's bitplanes in the
  1018.                Playing / video Config menu.
  1019.                If you have JACOsub set for a 4-color (2-bitplane) screen,
  1020.                and you try to load in a 16-color (4-bitplane) picture, you
  1021.                will lose 2 biplanes of information, and the picture will
  1022.                look strange when it appears.
  1023.            4.  All pictures are treated as brushes.  Therefore, your
  1024.                picture, once loaded, will use JACOsub's color palette.  THE
  1025.                PICTURE'S OWN COLOR PALETTE WILL BE IGNORED.  Create your
  1026.                graphics using the SAME palette you use with JACOsub or the
  1027.                picture will look strange when it appears.  If you want to
  1028.                load a picture with its own colors, use the RLG directive
  1029.                (but then you won't be able to display text on top of it).
  1030.            5.  JACOsub attempts to load graphic files as they are needed.
  1031.                This can cause a slight video switch delay if a time event
  1032.                occurs while a file is loading, even though the graphic
  1033.                loading routines do check the clock frequently.  Keep your
  1034.                images on a fast hard disk, or better yet, in RAM:.  If you
  1035.                do not have sufficient memory, then do not use this
  1036.                directive!
  1037.  
  1038.     RLG <ILBM file name>
  1039.            Load an IFF (Amiga) or PCX (MSDOS) graphic file into memory to
  1040.            to be displayed, in all its glory, at the appropriate time.
  1041.            On the Amiga, the picture will temporarily replace one video
  1042.            buffer.  Under MSDOS, the file is loaded into one of the
  1043.            buffers.  As with RLB, JACOsub assumes that the text following
  1044.            the RLG directive contains the file name to load.  JACOsub will
  1045.            attempt to center the picture on your display.
  1046.  
  1047.            The RLB caveats 1, 2, and 5 above apply here also, and the RLG
  1048.            directive has some additional considerations:
  1049.  
  1050.            1.  You cannot display text on top of a picture loaded with
  1051.                the RLG directive.  Use the RLB directive for this.
  1052.            2.  The time ranges associated with a graphic screen should NOT
  1053.                overlap any other time ranges.  If they do, the start time
  1054.                for the graphic has priority over any unrealized end times.
  1055.            3.  (MSDOS only) This directive loads a PCX file into one of the
  1056.                video buffers.  The picture MUST be the same resolution and
  1057.                color depth as your display mode.  That's 640x400x256 for
  1058.                HIRES, or 800x600x16 for SUPERHIRES.
  1059.            4.  (Amiga only) The RLG directive can tax your memory even more
  1060.                severely than RLB, especially if you load a pictures like
  1061.                hi-res HAM images to substitute every video buffer.
  1062.            5.  (Amiga only) We observe difficulty loading Extra-Halfbrite
  1063.                pictures.  Try it.  HAM and AGA images seem to work OK.
  1064.  
  1065.     RDB <LeftEdge> <TopEdge> <RightEdge> <BottomEdge>
  1066.            Draw a solid rectangle in the current text color with diagonal
  1067.            corners at the coordinates specified.  Coordinate units are
  1068.            percentages of the display width and height.  This is useful
  1069.            for making video letterbox margins really black.  To make the
  1070.            rectangle appear behind text, be sure it occurs in the script
  1071.            physically before the text, with a start time less than or equal
  1072.            to the text start time.
  1073.  
  1074.     RX <ARexx script name>
  1075. (Amiga)    Execute the ARexx script name that follows the RX directive.
  1076.            You should not specify other directives on the same line.  Only
  1077.            one RX directive may be specified per time event -- that is, if
  1078.            you have several lines all sharing the same start time, no more
  1079.            than one of them may contain an RX directive.  If more than one
  1080.            RX directive is specified for a given start time, the one that
  1081.            occurs latest in the script will be used.  The end time for the
  1082.            line is ignored, but should be larger than the start time to
  1083.            avoid a compiler warning.  Try to make the end time equal to the
  1084.            next nearest start time to avoid creating unnecessary video
  1085.            frames.
  1086.  
  1087. Default directives
  1088. ------------------
  1089.  
  1090. Because all of the above directives are optional, there is one other set of
  1091. directives that may be used when you do not wish to specify any:
  1092.  
  1093.     D or D0   Default.  To be used if no other directives are used.  You
  1094.            don't even need this directive at all, if your text begins with
  1095.            a non-alphabetic character (such as a {comment}, number, etc.).
  1096.  
  1097.            Specifying D (or nothing) will use the program's default
  1098.            settings.  The default directive for JACOsub is normally
  1099.  
  1100.            HL1HR99VH100VT16VB16JCJBFW1E0F0FDFB1FO0:2FSSE0SNCF3CB0CP0CS0:0:2
  1101.  
  1102.            which you can change in the file JACOsub.Config, or with a #D
  1103.            command at the top of your script.  Confused?  Here they are
  1104.            spaced out:
  1105.  
  1106.            HL1 HR99 VH100 VT16 VB16 JC JBF W1 E0
  1107.            F0 FD FB1 FO0:2 FSSE0 SN CF3 CB0 CP0 CS0:0:2
  1108.  
  1109.            The R directives and the Genlock directives should NEVER be
  1110.            specified globally, nor in JACOsub.Config.
  1111.  
  1112.     Dn     The directives D1 - D30 may be defined with the commands
  1113.            #D1 - #D30.  You can use these "default" directives as shorthand
  1114.            for more complex directives that you may need in many places.
  1115.            If you put two D directives in the same directive string, the
  1116.            latest one will be used, and any previous directives ignored.
  1117.  
  1118.    [name]  A name enclosed in square brackets may be substituted for any
  1119.            of the D directives.  You must have previously defined this
  1120.            name when you defined the D directive.
  1121.  
  1122. Other directives may be appended to a D directive to modify the behavior
  1123. of that D directive.  For example, if you defined a directive to use font
  1124. 0 and color 1, and decided to name it "credits" then you would say:
  1125.  
  1126.    #D2 F0CF1 credits
  1127.  
  1128. Then, if you wanted to use the D2 (or "credits") directive with font 3
  1129. instead of font 0, you could modify the directive either of the following
  1130. two ways:
  1131.  
  1132.    0:00:12.01 0:00:19.20 D2F3        Leia performed Akira's voice.
  1133. or 0:00:12.01 0:00:19.20 [Credits]F3 Leia performed Akira's voice.
  1134.  
  1135. You can spell the directive name using uppercase or lowercase characters.
  1136.  
  1137. If a directive string contains conflicting information, the information
  1138. occurring last will be used.  For example, VTD will cause VT to be ignored
  1139. in favor of the default.  In the directive CF10JLCF3, CF10 will be ignored
  1140. in favor of CF3.  Naturally, any directive beginning with D is unaffected
  1141. by the D.  In the long default directive above, you can see VT16VB16.  This
  1142. serves to set the top-of-screen offset to 16 for later, and then sets the
  1143. default vertical positioning at 16 pixels from the bottom of the viewport.
  1144.  
  1145. Time track
  1146. ----------
  1147.  
  1148.     Tx     Designate this line as belonging to track x, where x is any of
  1149.            the characters 0-9, A-F (case insensitive), or punctuation.
  1150.            This directive is ignored when compiling and playing scripts.
  1151.            All titles default to T0 if no track is specified.
  1152.  
  1153. The purpose of tracks is to let you assign unique designations to specific
  1154. title sequences interwoven with others in your script so that you can time
  1155. them separately.
  1156.  
  1157. For example, suppose you need to subtitle two people talking simultaneously
  1158. with music lyrics in the background.  This requires three independent
  1159. timing sequences.  There are two ways to do this:
  1160.  
  1161. 1.  Separate blocks of titles.  Without using the T directive, you must
  1162.     arrange each sequence as a separate block of titles (remember, JACOsub
  1163.     doesn't care about order of the titles in your script file -- it will
  1164.     sort everything out according to start and stop times).
  1165.  
  1166. 2.  One block of titles containing designated time tracks.  You can weave
  1167.     all the titles together as one long sequence, and designate separate
  1168.     tracks with the T directive so that the timing procedure can figure out
  1169.     which titles must be timed, and which must be skipped.
  1170.  
  1171. TRACKS WILL BE IGNORED IN ALL DEFAULT OR USER-DEFINED DIRECTIVES.
  1172. Furthermore, as far as JACOsub is concerned, trackes are not treated
  1173. internally as true directives at all.  Their only use is to flag lines for
  1174. the program's timing functions.
  1175.  
  1176.  
  1177. 5.  SAMPLE LINES
  1178. ================
  1179.  
  1180. These 4 lines all have the same effect.  Note that any spaces after the
  1181. directive and the first space after comments are ignored.
  1182.  
  1183. 0:00:10.11 0:00:12.00 D  {fudo-ikiteru} It's alive!
  1184. 0:00:10.11 0:00:12.00 D  {fudo-ikiteru}It's alive!
  1185. 0:00:10.11 0:00:12.00 D  It's alive!{line doesn't start with a comment}
  1186. 0:00:10.11 0:00:12.00    {fudo-ikiteru} It's alive!{starts with a comment}
  1187. 0:00:10.11 0:00:12.00 [default] {fudo-ikiteru} It's alive!\
  1188.                       {this assumes the D directive was named to "default"}
  1189.  
  1190. If you want leading/trailing spaces, all of these lines will do the same
  1191. thing (put two spaces in front of and after the text):
  1192.  
  1193. 0:00:10.11 0:00:12.00 D  ~~{fudo-ikiteru} It's alive! ~
  1194. 0:00:10.11 0:00:12.00 D  {fudo-ikiteru}~~It's alive!~~
  1195. 0:00:10.11 0:00:12.00 D  {fudo-ikiteru} ~~It's alive!~~
  1196. 0:00:10.11 0:00:12.00 D ~ It's alive!~~
  1197. 0:00:10.11 0:00:12.00 ~~{fudo-ikiteru} It's alive! ~
  1198. 0:00:10.11 0:00:12.00  {fudo-ikiteru}~ It's alive!~~
  1199. 0:00:10.11 0:00:12.00  {fudo-ikiteru} ~~It's alive!~~
  1200. 0:00:10.11 0:00:12.00  {fudo-ikiteru}   It's alive!~~
  1201.  
  1202. THE FOLLOWING LINE IS BAD.  It needs either a directive after the timing
  1203. numbers, or a comment to indicate that subtitle text follows the timing
  1204. numbers.  Any alphabet character (A-Z, a-z) following the timing numbers
  1205. MUST be part of a directive.
  1206.  
  1207. 0:00:10.11 0:00:12.00  It's alive!
  1208.  
  1209. For the next line, use color 1 for the font face color, start the
  1210. subtitle at the top of the screen and leave the other defaults alone,
  1211. and cause one word to be displayed in italics:
  1212.  
  1213. 0:02:23.23 0:02:25.01 cf1vt {thug1-nani} Whaddaya \Imean\N, ``please?''
  1214.  
  1215. Note:  Normal quotation marks ("like this") may be used, but using a
  1216. double grave and a double apostrophe, as in the line above, looks more
  1217. professional on the screen.  Just make sure that the grave looks like an
  1218. upside-down apostrophe in your font, and that both characters occupy a
  1219. narrow space.  The JACOsub fonts are designed this way.
  1220.  
  1221. Additional note (THIS IS ONE OF THE BIG FEATURES OF JACOsub):
  1222. Timings may overlap!  The software will handle overlapping text displays
  1223. properly, but you must be sure to position your subtitles so that these
  1224. separate text events do not physically overlap on the screen.  You can
  1225. arrange timed lines in any order you want, separate overlapped events
  1226. into groups, or whatever.  The program will handle it.
  1227.  
  1228.  
  1229. 6.  CREDITS
  1230. ===========
  1231.  
  1232. The original JACOsub format was dreamed up by Alex Matulich and Daric
  1233. Koslowski, before any code was ever written for JACOsub.  Yes, this was the
  1234. second step!  (The first was to create the fonts.)  Beta testers and users
  1235. have been very helpful in expanding and improving the specification into
  1236. what it is today.  User feedback has played a large role in the development
  1237. of the software and the script format.  The entire JACOsub project has been
  1238. largely user-driven.
  1239.  
  1240. End of JScripts.doc.
  1241.